Skip Headers

Oracle® HTML DB User's Guide Release 2.0 Part Number B16373-01 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# 13 Managing Security

You can provide security for your application through cross-site scripting protection, session state protection, authentication, and authorization.

This section contains the following topics:

- About Cross-Site Scripting Protection

- Understanding Session State Protection

- Establishing User Identity Through Authentication

- Providing Security Through Authorization

## About Cross-Site Scripting Protection

Cross site-scripting (also referred to as XSS) is a security breach that takes advantage of dynamically generated Web pages. In a XSS attack, a Web application is sent a script that activates when it is read by a user's browser. Once activated, these scripts can steal data, or even session credentials and return the information to the attacker. If malicious code were introduced into an Oracle HTML DB application, it could be rendered into HTML regions and other places within the application during normal page rendering. To prevent the introduction of malicious code into session state, the HTML DB engine escapes characters in certain cases.

Topics in this section include:

- Protecting HTML Regions and Other Static Areas

- Protecting Dynamic Output

- Protecting Report Regions

- Protecting Form Items

- Remembering to Follow Best Practices

### Protecting HTML Regions and Other Static Areas

In HTML regions and other static display areas, you can reference session state using the `&ITEM.` notation. Examples of static displays areas include HTML regions, page headers and footers, region headers and footers, region titles, button labels, help text, form item labels and post-element text, templates, radiogroup (before and after field text), event success messages, event error messages, navigation bar attributes, application static substitution string values, chart labels and legends, breadcrumbs and list framing text, and calendar text, labels, or legends.

#### Using the Cross-Site Scripting Protection Attribute

You can control whether items are escaped when they are rendered using the Cross-Site Scripting Protection attribute on the Edit Page Item page.

To enable cross-site scripting protection:

1. Navigate to the appropriate Page Definition:

   1. Navigate to the Workspace home page.

   2. Click the Application Builder icon.

   3. Select an application.

   4. Select a page.

      The Page Definition appears.

2. Under Items, select the item name.

   The attributes page for the item appears.

3. Scroll down to Security.

4. From Cross-Site Scripting Protection select one of the following:

   - Yes - Indicates the item is deemed safe to render exactly as is when fetched from session state. If you select Yes, the item is escaped when it is passed into session state using an `f?p` URL or when saved in session state when it is submitted on the page.

   - No - Specifies the item should be escaped when it is rendered. If you select No, the item is not escaped when it is passed into session state using an `f?p` URL or saved in session state when it is submitted on the page.

5. Click Apply Changes.

Note: Application-level items have an implicit setting of Yes for this attribute which cannot be changed.

### Protecting Dynamic Output

Items fetched from session state and rendered using `htp.p` or other methods should be explicitly escaped by the code where it is appropriate to do so. For example, suppose PL/SQL dynamic content region on a page uses the following:

    htp.p(v('SOME_ITEM'));

If the value of the item fetched from session state could contain unintended tags or script, you might want to use the following in the region:

    htp.p(htf.escape_sc(v('SOME_ITEM'));

However, if you are confident that the fetched value is safe for rendering, you do not need to escape the value. As a developer, you need to determine when it is appropriate to not escape output.

### Protecting Report Regions

The Oracle HTML DB escapes data rendered in the body of a report. References to session state in report headings and messages, are fetched from session state using a method that assumes that referenced values have the Cross-Site Scripting Protection attribute enabled. In other words, these values are not escaped when they are fetched because it is assumed that they have been escaped on input. As you create reports, it is important you understand this assumption and not reference items in reports for which the Cross-Site Scripting Protection attribute is set to No.

### Protecting Form Items

When form items, including hidden items, obtain their values during page rendering, the resulting string is escaped before rendering. The only exception are items of display type Display as Text (does not save state), which are not escaped.

Items having the display type Display as Text (does not save state) feature a unique escape on input behavior. These items obtain values containing HTML or script by way a page computation, page processes, or source and default values from within an application, but they cannot obtain values using `f?p` URLs or by POSTing them. This behavior makes them a good choice for framing text values in HTML markup or for including JavaScript.

### Remembering to Follow Best Practices

As an added precaution, always follow best practices to guard against cross-site scripting attacks. For example, during the development process think about whether or not an item could have malicious content stored in it by URL tampering or another means. Avoid referencing form items using `&MY_ITEM.` for rendering in most types of static areas since it can lead to security vulnerabilities. Instead, use application-level items or page items of type Display as text (does not save state). Another easy safeguard is to escape less than (`<`), greater than (`>`), and ampersands (`&`).

## Understanding Session State Protection

Session State Protection is a built-in functionality that prevents hackers from tampering with the URLs within your application. URL tampering can adversely affect program logic, session state contents, and information privacy.

Enabling Session State Protection is a two step process. First, you enable the feature. Second, you set page and item security attributes.

Topics in this section include:

- How Session State Protection Works

- Enabling Session State Protection

- Configuring Session State Protection

### How Session State Protection Works

When enabled, Session State Protection uses the Page Access Protection attributes and the Session State Protection item attributes in conjunction with checksums positioned in `f?p=` URLs to prevent URL tampering and unauthorized access to and alteration of session state. When Session State Protection is disabled, the page and item attributes related to session state protection are ignored and checksums are not included checksums in generated `f?p=` URLs.

### Enabling Session State Protection

You can enable session state protection from either the Edit Security Attributes page or the Session State Protection page.

Enabling Session State Protection is a two step process. First, you enable the feature. Second, you set page and item security attributes. You can perform these steps using a wizard, or you can set security attributes for pages and items manually on the Session State Protection page.

Topics in this section include:

- Enabling Session State Protection from Edit Security Attributes

- Enabling Session State Protection from Session State Protection

#### Enabling Session State Protection from Edit Security Attributes

To enable Session State Protection from the Edit Security Attributes page:

1. Click the Application Builder icon on Workspace home page.

2. Select an application.

3. Click Edit Attributes.

4. Click Edit Security Attributes.

5. Scroll down to Session State Protection and select Enabled from the Session State Protection list.

6. To configure session Session State Protection, click Manage Session State Protection.

   The Session State Projection page appears.

7. Navigate to the Edit Security Attributes page to set page and item security attributes.

Tip: To disable Session State Protection, perform the previous steps again, but select Disabled instead of Enabled. Disabling Session State Protection will not change existing security attribute settings, but those attributes will be ignored at runtime.

##### About the Expire Bookmarks Button

Enabling Session State Protection affects whether or not bookmarked links to the current application will work. Consider the following rules:

1. Bookmarked links created after Session State Protection is enabled will work if the bookmarked link contains a checksum.

2. Bookmarked links created before Session State Protection is enabled will not work if the bookmarked link contains a checksum.

3. Bookmarks that do not contain checksums or contain unnecessary checksums will not be affected by Session State Protection.

During page rendering, the HTML DB engine uses a hidden application attribute (a checksum salt) during computation and to verify checksums included in `f?p` URLs. When you enable Session State Protection, the HTML DB engine includes checksums. You can reset the checksum salt attribute by clicking Expire Bookmarks on the Edit Security Attributes page. Note that if you click Expire Bookmarks, bookmarked URLs used to access your application that contain previously generated checksums will fail.

#### Enabling Session State Protection from Session State Protection

To enable Session State Protection:

1. Navigate to the Shared Components page:

   1. Click the Application Builder icon on Workspace home page.

   2. Select an application.

   3. Under Security, select Session State.

      The Session State Protection page appears. Note the current Session State Protection status (Enabled or Disabled) displays at the top of the page.

2. Click the Set Protection button.

   The Session State Protection wizard appears.

3. Under Select Action, select Enable and click Next.

   Next, determine whether to set security attributes for pages and items.

4. Select Enable and click Next.

5. Click Enable Session State Protection.

Tip: To disable Session State Protection, perform the same steps, but select Disable instead of Enable. Disabling Session State Protection will not change existing security attribute settings, but will be ignore them at run time.

### Configuring Session State Protection

Once you have enabled Session State Protection, the next step is to configure security attributes. You can configure security attributes in two ways:

- Use a wizard and select a value for specific attribute categories. Those selections will then be applied to all pages and items within the application.

- Configure values for individual pages, items, or application items.

Topics in this section include:

- Reviewing Existing Session State Protection Settings

- Configuring Session State Protection Using a Wizard

- Configuring Session State Protection for Pages

- Configuring Session State Protection for Items

- Configuring Session State Protection for Application Items

Tip: Before you can configure security attributes, you must first enable Session State Protection. See "Enabling Session State Protection".

#### Reviewing Existing Session State Protection Settings

You can review a summary of Session State Protection settings for pages, items, and application items on the first page of the Session State Protection wizard.

To view summaries of existing Session State Protection settings:

1. Navigate to the Session State Protection page:

   1. Click the Application Builder icon on Workspace home page.

   2. Select an application.

   3. Click Shared Components.

   4. Under Security, select Session State Protection.

      The Session State Protection page appears.

2. Click Set Protection.

3. Expand the following reports at the bottom of the page:

   - Page Level Session State Protection Summary

   - Page Item Session State Protection Summary

   - Application Item Session State Protection

#### Configuring Session State Protection Using a Wizard

When you configure Session State Protection using a wizard, you set a value for specific attribute categories. Those selections are then applied to all pages and items within the application.

To configure Session State Protection using a wizard:

1. Navigate to the Session State Protection page:

   1. Click the Application Builder icon on Workspace the home page.

   2. Select an application.

   3. Click Shared Components.

   4. Under Security, select Session State Protection.

      The Session State Protection page appears.

2. Click Set Protection.

   The Session State Protection wizard appears.

3. Under Select Action, select Configure and click Next.

4. For Page Access Protection, select one of the following:

   - Unrestricted - The page may be requested using an URL with or without session state arguments (Request, Clear Cache, Name/Values).

   - Arguments Must Have Checksum - If Request, Clear Cache, or Name/Value arguments appear in the URL, a checksum must also be provided. The checksum type must be compatible with the most stringent Session State Protection attribute of all the items passed as arguments.

   - No Arguments Allowed - A URL may be used to request the page but no Request, Clear Cache, or Name/Value arguments are allowed.

   - No URL Access - The page may not be accessed using a URL, however the page may be the target of a Branch to Page branch type, which does not do a URL redirect.

5. For Application Item Protection, select one of the following:

   - Unrestricted - The item's session state may be set by passing the item name/value in a URL or in a form. No checksum is required in the URL.

   - Checksum Required: Application Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the workspace and application. A user-level checksum or a session-level checksum will also suffice (see next bullets). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by any user running the same application in the current workspace but in a different session.

   - Checksum Required: User Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the workspace, application, and user. A session-level checksum will also suffice (see next bullet). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by the same named user, running the same application in the current workspace but in a different session.

   - Checksum Required: Session Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the current session. Use this option when you want to allow this item to be set only by URLs having checksums that were generated in the current session.

   - Restricted - May not be set from browser - The item may not be altered using the URL or POSTDATA. Use this option when you want to restrict the way that the item value can be set to internal processes, computations, and so on. This attribute is applicable only to items that cannot be used as data entry items and is always observed even if Session State Protection is disabled.

     Use this attribute for application items or for page items with any of these Display As types:

     - Display as Text (escape special characters, does not save state)

     - Display as Text (does not save state)

     - Display as Text (based on LOV, does not save state)

     - Display as Text (based on PLSQL, does not save state)

     - Text Field (Disabled, does not save state)

     - Stop and Start HTML Table (Displays label only)

6. For Page Data Entry Item Protection, select one of the following:

   - Unrestricted - The item's session state may be set by passing the item name/value in a URL or in a form. No checksum is required in the URL.

   - Checksum Required: Application Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the workspace and application. A user-level checksum or a session-level checksum will also suffice (see next bullets). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by any user running the same application in the current workspace but in a different session.

   - Checksum Required: User Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the workspace, application, and user. A session-level checksum will also suffice (see next bullet). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by the same named user, running the same application in the current workspace but in a different session.

   - Checksum Required: Session Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the current session. Use this option when you want to allow this item to be set only by URLs having checksums that were generated in the current session.

7. For Page Display-Only Item Protection, select one of the following:

   - Unrestricted - The item may be set by passing the item name/value in a URL or in a form. No checksum is required in the URL.

   - Checksum Required: Application Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the workspace and application. A user-level checksum or a session-level checksum will also suffice (see next bullets). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by any user running the same application in the current workspace but in a different session.

   - Checksum Required: Session Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the current session. Use this option when you want to allow this item to be set only by URLs having checksums that were generated in the current session.

   - Checksum Required: User Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the workspace, application, and user. A session-level checksum will also suffice (see next bullet). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by the same named user, running the same application in the current workspace but in a different session.

   - Restricted: May not be set from browser - The item may not be altered using the URL or POSTDATA. Use this when you want to restrict the way that the item value can be set to internal processes, computations, and so on. This attribute is always observed, even if Session State Protection is disabled.

     This attribute may be used with any of these Display As types:

     - Display as Text (escape special characters, does not save state)

     - Display as Text (does not save state)

     - Display as Text (based on LOV, does not save state)

     - Display as Text (based on PLSQL, does not save state)

     - Text Field (Disabled, does not save state)

     - Stop and Start HTML Table (Displays label only)

8. Click Next.

9. Click Finish.

#### Configuring Session State Protection for Pages

To configure Session State Protection for Pages:

1. Navigate to the Session State Protection page:

   1. Click the Application Builder icon on Workspace home page.

   2. Select an application.

   3. Click Shared Components.

   4. Under Security, select Session State Protection.

      The Session State Protection page appears.

2. Click the Page icon.

3. To filter the view, use the Page, Display, and Page Access Protection lists at the top of the page.

4. Select a page ID.

   The Set Page and Item Protection page appears. The following information displays at the top of the page:

   - Application ID and name

   - Session State Protection status (Enabled or Disabled)

   - Page ID

   - Page name

5. For Page Access Protection, select one of the following:

   - Unrestricted - The page may be requested using an URL with or without session state arguments (Request, Clear Cache, Name/Values).

   - Arguments Must Have Checksum - If Request, Clear Cache, or Name/Value arguments appear in the URL, a checksum must also be provided. The checksum type must be compatible with the most stringent Session State Protection attribute of all the items passed as arguments.

   - No Arguments Allowed - A URL may be used to request the page but no Request, Clear Cache, or Name/Value arguments are allowed.

   - No URL Access - The page may not be accessed using a URL, however the page may be the target of a Branch to Page branch type, which does not do a URL redirect.

6. For Item Types, select Data Entry Items or Display-only Items.

   Data Entry items are items that can be altered using forms and include hidden items. Display-Only items are rendered only and are not submitted with the form.

7. If you select Data Entry Items, select a session state protection level for each item:

   - Unrestricted - The item's session state may be set by passing the item name/value in a URL or in a form. No checksum is required in the URL.

   - Checksum Required: Application Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the workspace and application. A user-level checksum or a session-level checksum will also suffice (see next bullets). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by any user running the same application in the current workspace but in a different session.

   - Checksum Required: User Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the workspace, application, and user. A session-level checksum will also suffice (see next bullet). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by the same named user, running the same application in the current workspace but in a different session.

   - Checksum Required: Session Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the current session. Use this option when you want to allow this item to be set only by URLs having checksums that were generated in the current session.

8. If you select Display-only Item, select a session state protection level for each item:

   - Unrestricted - The item may be set by passing the item name/value in a URL or in a form. No checksum is required in the URL.

   - Restricted: May not be set from browser - The item may not be altered using the URL or POSTDATA. Use this when you want to restrict the way that the item value can be set to internal processes, computations, and so on. This attribute is always observed, even if Session State Protection is disabled. This attribute may be used with any of these Display As types:

     - Display as Text (escape special characters, does not save state)

     - Display as Text (does not save state)

     - Display as Text (based on LOV, does not save state)

     - Display as Text (based on PLSQL, does not save state)

     - Text Field (Disabled, does not save state)

     - Stop and Start HTML Table (Displays label only)

   - Checksum Required: Application Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the workspace and application. A user-level checksum or a session-level checksum will also suffice (see next bullets). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by any user running the same application in the current workspace but in a different session.

   - Checksum Required: User Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the workspace, application, and user. A session-level checksum will also suffice (see next bullet). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by the same named user, running the same application in the current workspace but in a different session.

   - Checksum Required: Session Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the current session. Use this option when you want to allow this item to be set only by URLs having checksums that were generated in the current session.

9. Click Apply Changes.

#### Configuring Session State Protection for Items

To configure Session State Protection for items:

1. Navigate to the Session State Protection page:

   1. Click the Application Builder icon on Workspace home page.

   2. Select an application.

   3. Click Shared Components.

   4. Under Security, select Session State Protection.

      The Session State Protection page appears.

2. Click the Item icon.

3. To filter the view, select from the Page, Display, and Item Session State Protection lists at the top of the page and click Go.

4. Select a page ID.

   The Edit Session State Protection for Page and Items page appears. The following information displays at the top of the page:

   - Application ID and name

   - Session State Protection status (Enabled or Disabled)

   - Page ID

   - Page name

5. For Page Access Protection, select a session state protection level for each item:

   - Unrestricted - The page may be requested using an URL with or without session state arguments (Request, Clear Cache, Name/Values).

   - Arguments Must Have Checksum - If Request, Clear Cache, or Name/Value arguments appear in the URL, a checksum must also be provided. The checksum type must be compatible with the most stringent Session State Protection attribute of all the items passed as arguments.

   - No Arguments Allowed - A URL may be used to request the page but no Request, Clear Cache, or Name/Value arguments are allowed.

   - No URL Access - The page may not be accessed using a URL, however the page may be the target of a Branch to Page branch type, which does not do a URL redirect.

6. For Item Types, select Data Entry Items or Display-only Items.

   Data Entry items are items that can be altered using forms and include hidden items. Display-Only items are rendered only and are not submitted with the form.

7. If you select Data Entry Items, select a session state protection level for each item:

   - Unrestricted - The item's session state may be set by passing the item name/value in a URL or in a form. No checksum is required in the URL.

   - Checksum Required: Application Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the workspace and application. A user-level checksum or a session-level checksum will also suffice (see next bullets). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by any user running the same application in the current workspace but in a different session.

   - Checksum Required: User Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the workspace, application, and user. A session-level checksum will also suffice (see next bullet). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by the same named user, running the same application in the current workspace but in a different session.

   - Checksum Required: Session Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the current session. Use this option when you want to allow this item to be set only by URLs having checksums that were generated in the current session.

8. If you select Display-only Item, select a session state protection level for each item:

   - Unrestricted - The item may be set by passing the item name/value in a URL or in a form. No checksum is required in the URL.

   - Restricted: May not be set from browser - The item may not be altered using the URL or POSTDATA. Use this when you want to restrict the way that the item value can be set to internal processes, computations, and so on. This attribute is always observed, even if Session State Protection is disabled. This attribute may be used with any of these Display As types:

     - Display as Text (escape special characters, does not save state)

     - Display as Text (does not save state)

     - Display as Text (based on LOV, does not save state)

     - Display as Text (based on PLSQL, does not save state)

     - Text Field (Disabled, does not save state)

     - Stop and Start HTML Table (Displays label only)

   - Checksum Required: Application Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the workspace and application. A user-level checksum or a session-level checksum will also suffice (see next bullets). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by any user running the same application in the current workspace but in a different session.

   - Checksum Required: User Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the workspace, application, and user. A session-level checksum will also suffice (see next bullet). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by the same named user, running the same application in the current workspace but in a different session.

   - Checksum Required: Session Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the current session. Use this option when you want to allow this item to be set only by URLs having checksums that were generated in the current session.

9. Click Apply Changes.

#### Configuring Session State Protection for Application Items

To configure Session State Protection for application items:

1. Navigate to the Session State Protection page:

   1. Click the Application Builder icon on Workspace home page.

   2. Select an application.

   3. Click Shared Components.

   4. Under Security, select Session State Protection.

      The Session State Protection page appears.

2. Click the Application Item icon.

3. Select an application item.

4. Under Security, select one of the following from the Session State Protection list:

   - Unrestricted - The item's session state may be set by passing the item name/value in a URL or in a form. No checksum is required in the URL.

   - Restricted - May not be set from browser - The item may not be altered using the URL or POSTDATA. Use this option when you want to restrict the way that the item value can be set to internal processes, computations, and so on. This attribute is only applicable only to items that cannot be used as data entry items and is always observed even if Session State Protection is disabled. This attribute may be used for application items or for page items with any of these Display As types:

     - Display as Text (escape special characters, does not save state)

     - Display as Text (does not save state)

     - Display as Text (based on LOV, does not save state)

     - Display as Text (based on PLSQL, does not save state)

     - Text Field (Disabled, does not save state)

     - Stop and Start HTML Table (Displays label only)

   - Checksum Required: Application Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the workspace and application. A user-level checksum or a session-level checksum will also suffice (see next bullets). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by any user running the same application in the current workspace but in a different session.

   - Checksum Required: User Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the workspace, application, and user. A session-level checksum will also suffice (see next bullet). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by the same named user, running the same application in the current workspace but in a different session.

   - Checksum Required: Session Level - The item's session state may be set by passing the item name/value in a URL if a checksum is also provided that is specific to the current session. Use this option when you want to allow this item to be set only by URLs having checksums that were generated in the current session.

5. Click Apply Changes.

## Establishing User Identity Through Authentication

Authentication is the process of establishing each user's identify before they can access your application. Authentication may require a user identify a username and password or could involve the use of digital certificates or a secure key.

When you create an authentication scheme, you have the option of choosing from a number of preconfigured authentication schemes, copying an authentication scheme from an existing application, or creating your own custom authentication scheme.

Topics in this section include:

- Understanding How Authentication Works

- Determining Whether to Include Authentication

- Creating an Authentication Scheme

- Using the Authentication Scheme Repository

- Viewing the Current Authentication Scheme for an Application

- Changing the Current Authentication Scheme for an Application

- Viewing Authentication Scheme Utilization

- About Preconfigured Authentication Schemes

- About Creating an Authentication Scheme from Scratch

### Understanding How Authentication Works

You determine how your application interacts with users. If all users have the same rights and privileges they are referred to as public users. However, if your application needs to track each user individually, you need to specify an authentication method.

Authentication establishes the identity of each user who accesses your application. Many authentication processes require a user provide some type of credentials such as a username and password. These credentials are then evaluated and they either pass or fail. If the credentials pass, the user has access to the application. Otherwise, access is denied.

Once a user has been identified, the HTML DB engine keeps track of each user by setting the value of the built-in substitution string `APP_USER`. As a user navigates from page to page, the HTML DB engine sets the value of `APP_USER` to identify the user. The HTML DB engine uses `APP_USER` as one component of a key for tracking each user's session state.

From a programming perspective, you can access `APP_USER` using the following syntax:

- From PL/SQL:

      V('APP_USER')

- As a bind variable from either PL/SQL or SQL:

      :APP_USER

You can use `APP_USER` to perform your own security checks and conditional processing. For example, suppose you created the following table:

    CREATE TABLE my_security_table (
      user_id   VARCHAR2(30),
      privilege VARCHAR2(30));

Once created, you could populate this table with user privilege information and then use it to control the display of pages, tabs, navigation bars, buttons, regions, or any other control or component.

See Also: "APP_USER" and "Configuring Security Attributes"

### Determining Whether to Include Authentication

As you create your application, you need to determine whether to include authentication. You can:

- Choose to not require authentication. Oracle HTML DB does not check any user credentials. All pages of your application are accessible to all users.

- Select a built-in authentication scheme. Create an authentication method based on available preconfigured authentication schemes. Depending on which scheme you choose, you may also have to configure the corresponding components of Oracle 10giAS, Oracle Internet Directory, or other external services.

- Create custom authentication scheme. Create a custom authentication method, giving you complete control over the authentication interface. To implement this approach, you must provide a PL/SQL function the HTML DB engine executes before processing each page request. This function's Boolean return value determines whether the HTML DB engine processes the page normally or displays a failure page.

### Creating an Authentication Scheme

To create an authentication scheme:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. On the Application home page, click Shared Components.

   The Shared Components page appears.

5. Under Security, select Authentication Schemes.

   The Authentication Schemes page appears.

6. To create a new authentication scheme, click Create.

7. Specify how the scheme should be created by selecting one of the following:

   - Based on preconfigured scheme

   - As a copy of an existing scheme

   - From scratch

8. Follow the on-screen instructions

See Also: "About Preconfigured Authentication Schemes" and "About Creating an Authentication Scheme from Scratch"

### Using the Authentication Scheme Repository

Once created, available authentication schemes display in the Authentication Schemes Repository.

To navigate to the Authentication Schemes Repository:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. On the Application home page, click Shared Components.

   The Shared Components page appears.

5. Under Security, select Authentication Schemes.

   The Authentication Schemes page appears. You can change the appearance of the page by making a selection from the View list. Available options include:

   - Icons (the default) displays each authentication scheme as a large icon. To edit an authentication scheme, click the appropriate icon.

   - Details displays each application item as a line in a report.

     In Details view you can:

     - Edit an authentication scheme by selecting the scheme name

     - View a list of the steps performed on each page by clicking the Show icon

     - Apply an authentication scheme to an application by clicking the make current link

### Viewing the Current Authentication Scheme for an Application

To view the current authentication scheme for an application:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. Click Edit Attributes.

5. Click Edit Security Attributes.

6. Locate the Authentication section. The current authentication scheme displays next to Authentication Scheme.

7. To link to the Authentication Scheme pages and select the scheme name.

### Changing the Current Authentication Scheme for an Application

To change the authentication scheme for an application:

1. Navigate to the Authentication Schemes:

   1. Click the Application Builder icon on the Workspace home page.

   2. Select an application.

   3. On the Application home page, click Shared Components.

      The Shared Components page appears.

   4. Under Security, select Authentication Schemes.

2. Click the Change Current tab at the top of the page.

3. Select a new authentication scheme and click Next.

4. Click Make Current.

### Viewing Authentication Scheme Utilization

The Authentication Schemes report lists authentication scheme utilization for all applications in the current workspace.

To view the Authentication Schemes report:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

   The Applications home page appears.

4. From the Tasks list, select View Application Reports.

5. Click Cross Application Reports.

6. Select Authentication Schemes.

7. Click the application ID to link to the appropriate Application home page.

### About Preconfigured Authentication Schemes

When you select a preconfigured authentication scheme, Oracle HTML DB creates an authentication scheme for your application that follows a standard behavior for authentication and session management. The following list describes available preconfigured authentication schemes:

- Open Door Credentials enables anyone to access your application using a built-in login page which captures a username. This can be useful during application development.

- HTML DB Account Credentials refers to the internal user accounts (also known as "cookie user" accounts) created and managed in the Oracle HTML DB user repository. Using method, your application can easily authenticate against these accounts.

- LDAP Credentials Verification requires you specify configuration parameters about the external Lightweight Directory Access Protocol (LDAP) directory you will be using.

- No Authentication (using DAD) gets the username from the data access descriptor (DAD), either as the value stored in the DAD configuration or, if the account information is not stored in the DAD configuration, as the username captured using the basic authentication challenge.

- Oracle Application Server Single Sign-On (HTML DB engine as Partner App) delegates authentication to the Oracle AS Single Sign-On (SSO) Server. To you use authentication scheme, your site must have already been registered as a partner application with the SSO server. For more information, contact your administrator.

- Oracle Application Server Single Sign-On (My application as Partner App) delegates authentication to the SSO server. Requires you register an application with SSO as a partner application.

#### About DAD Credentials Verification

DAD database authentication uses the Oracle database native authentication and user mechanisms to authenticate users using a basic authentication scheme. To use DAD credentials verification:

- Each application user must have a user account in the Oracle database.

- You must configure a PL/SQL DAD for basic authentication (without account information).

  This results in one username/password challenge for browser session for your application users. The user identity token is then made available in the `APP_USER` item.

DAD database authentication is useful when you need to implement an authentication method that requires minimal setup for a manageable number of users. Ideally these users would already have self-managed accounts in the database and your use of this authentication method would be short lived (for example, during the demonstration or prototyping stages of development).

The main drawback of this approach is burdensome account maintenance, especially if users do not administer their own passwords, or if their database accounts exist only to facilitate authentication to your application.

#### About HTML DB Account Credentials

HTML DB Account Credentials authentication uses internal user accounts (also known as "cookie user" accounts) created and managed in the Oracle HTML DB user repository. Workspace administrators can create and edit user accounts using the Manage Users page. HTML DB Account Credentials is a good solution when:

- You want control of the user account repository

- Username and password based approach to security is sufficient

- You do not need to integrate into a single sign-on framework

This is an especially good approach when you need to get a group of users up and running on a new application quickly.

See Also: "Managing Users" for information about creating and managing user accounts

#### About LDAP Credentials Verification

Any authentication scheme that uses a login page may be configured to use Lightweight Directory Access Protocol (LDAP) to verify the username and password submitted on the login page. Application Builder includes wizards and edit pages that explain how to configure this option. These wizards assume that an LDAP directory accessible to your application for this purpose already exists and that it can respond to a `SIMPLE_BIND_S` call for credentials verification. When you create a LDAP Credentials authentication scheme, the wizard requests and saves the LDAP host name, LDAP port, and the DN string. An optional pre-processing function can be specified to adjust formatting of the username passed to the API.

#### About Single Sign-On Server Verification

Oracle HTML DB applications can operate as partner applications with Oracle Application Server's Single Sign-On (SSO) infrastructure. To accomplish this, you must register your application (or register the HTML DB engine) as the partner application. To register your application or the HTML DB engine as a partner application, follow the Oracle Application Server instructions for registering partner applications and install the Oracle 9iAS SSO Software Developer Kit (SDK).

If you choose this approach, your application will not use an integrated login page. Instead, when a user accesses your application in a new browser session, the HTML DB engine redirects to the Single Sign-On login page. After the user is authentication by SSO, the SSO components redirect back to your application, passing the user identity and other information to the HTML DB engine. The user can then continue to use the application until they log off, terminate their browser session, or until some other session-terminating event occurs.

### About Creating an Authentication Scheme from Scratch

Creating an authentication scheme from scratch gives you complete control over your authentication interface. This is the best approach for applications when any of the following is true:

- Database authentication, or other methods are not adequate.

- You want to develop your own login form and associated methods.

- You want to delegate all aspects of user authentication to external services such as Oracle 10gAS Single Sign-On.

- You want to control security aspects of Oracle HTML DB session management.

- You want to record or audit activity at the user or session level.

- You want to enforce session activity or expiry limits.

- You want to program conditional n-way redirection logic before Oracle HTML DB page processing.

- You want to integrate your application with non-Oracle HTML DB applications using a common session management framework.

- Your application consists of multiple applications that operate seamlessly (for example, more than one Oracle HTML DB application ID).

See Also: "HTMLDB_CUSTOM_AUTH" for more information

#### About Session Management Security

When running custom authentication, Oracle HTML DB attempts to prevent two improper situations:

- Intentional attempts by a user to access session state belonging to someone else. However, users can still type in an arbitrary application session ID into the URL.

- Inadvertent access to a stale session state (probably belonging to the same user from an earlier time). This would commonly result from using bookmarks to application pages.

Oracle HTML DB checks that the user identity token set by the custom authentication function matches the user identity recorded when the application session was first created. If the user has not yet been authenticated and the user identity is not yet known, the session state being accessed does not belong to someone else. These checks determine whether the session ID in the request can be used. If not, the HTML DB engine redirects back the same page using an appropriate session ID.

#### Building a Login Page

When you create a new application in Oracle HTML DB, a login page is created. The alias for the page is `'LOGIN'`. You can use this page as the 'invalid session page' in an authentication scheme. The page is constructed with processes that call the Oracle HTML DB login API to perform credentials verification and session registration.

You can also build your own login pages using the pre-built pages as models and tailoring all of the user interface and processing logic to your requirements.

To create a login page for your application:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. Click Create Page.

5. Select Login Page.

6. Specify Login page attributes and click Create.

#### About Deep Linking

Deep linking refers to the ability to link to an Oracle HTML DB page out of context (for example, from a hyperlink in an e-mail or workflow notification). When you link to a page out of context and the application requires the user be authenticated, the user will be taken to the login page. After credentials verification, the HTML DB engine automatically displays the page that was referenced in the original link. Deep linking is supported for applications that use authentication schemes.

## Providing Security Through Authorization

Authorization is a broad term for controlling access to resources based on user privileges. While conditions control the rendering and processing of specific page controls or components, authorization schemes control user access to specific controls or components.

Topics in this section include:

- How Authorization Schemes Work

- Creating an Authorization Scheme

- Attaching an Authorization Scheme to an Application, Page, or Components

- Viewing Authorization Reports

### How Authorization Schemes Work

An authorization scheme extends the security of your application's authentication scheme. You can specify an authorization scheme for an entire application, a page, or specific control such as a region, item, or button. For example, you could use an authorization scheme to selectively determine which tabs, regions, or navigation bars a user sees.

An authorization scheme either succeeds or fails. If a component or control level authorization scheme succeeds, the user can view the component or control. If it fails, the user cannot view the component or control. If an application or page level authorization scheme fails, then Oracle HTML DB displays a previously defined message.

When you define an authorization scheme you give it a unique name. Once defined, you can attach it to any component or control in your application. To attach an authorization scheme to a component or control in your application, simply navigate to the appropriate attributes page and select an authorization scheme from the Authorization Scheme list.

### Creating an Authorization Scheme

Before you can attach an authorization scheme to an application or an application component or control, you must first create it.

To create an authorization scheme:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. On the Application home page, click Shared Components.

   The Shared Components page appears.

5. Under Security, select Authorization Schemes.

6. Click Create.

7. Specify how to create an authorization scheme by selecting one of the following:

   - From Scratch

   - As a Copy of an Existing Authorization Scheme

8. Follow the on-screen instructions.

#### Editing Attributes of an Existing Authorization Scheme

To edit attributes of an existing authorization scheme:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. On the Application home page, click Shared Components.

   The Shared Components page appears.

5. Under Security, select Authorization Schemes.

   The Authorization Schemes page appears. By default, each scheme displays as an icon.

6. To access a detail view of all schemes, select Details from the View list.

   The Authorization Schemes page appears. You can change the appearance of the page by making a selection from the View list. Available options include:

   - Icons (the default) displays each authentication scheme as a large icon. To edit an authorization scheme, click the appropriate icon.

   - Details displays each application item as a line in a report. To edit an authorization scheme, select the scheme name.

#### About the Evaluation Point Attribute

You can specify when your authorization scheme is validated in the Evaluation Point attribute. You can choose to have your authorization scheme validated once for each session or once for each page view.

Keep in mind, that if you specify that an authorization scheme should be evaluated once for each session and the authorization scheme passes, the underlying code, test, or query will not be executed again for the duration of the application session. If your authorization scheme consists of a test whose results might change if evaluated at different times during the session, then you should specify that the evaluation point be once for each page view.

#### About Resetting Authorization Scheme State

If an authorization scheme is validated once for each session, Oracle HTML DB caches the validation results in each user's session cache. You can reset a session's authorization scheme state by calling the `HTMLDB_UTIL.RESET_AUTHORIZATIONS` API.

Calling this procedure nulls out any previously cached authorization scheme results for the current session. Be aware that this procedure takes no arguments and is part of the publicly executable `HTMLDB_UTIL` package.

See Also: "RESET_AUTHORIZATIONS Procedure"

### Attaching an Authorization Scheme to an Application, Page, or Components

Once you have created an authorization scheme you can attach it to an entire application, page, control, or component.

Topics in this section include:

- Attaching an Authorization Scheme to an Application

- Attaching an Authorization Scheme to a Page

- Attaching an Authorization Scheme to a Control or Component

#### Attaching an Authorization Scheme to an Application

To attach an authorization scheme to an application:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. Click the Edit Attributes icon.

   The Application Attributes page appears.

5. Click the Edit Security Attributes icon.

6. Scroll down to Authorization and make a selection from the Authorization Scheme list.

#### Attaching an Authorization Scheme to a Page

To attach an authorization scheme to a page:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. Select a page.

5. Click Edit Attributes.

6. Scroll down to Security and make a selection from the Authorization Scheme list.

#### Attaching an Authorization Scheme to a Control or Component

To attach an authorization scheme to a page component or control:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. Select a page.

5. Click the name of the component or control to which you want to apply the authorization scheme.

6. Scroll down to Security and make a selection from the Authorization Scheme list.

### Viewing Authorization Reports

You can use the Authorization Scheme Subscription and Authorization Scheme Utilization reports to better manage authorization schemes within your application.

To view authorization scheme reports:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. On the Application home page, click Shared Components.

   The Shared Components page appears.

5. Under Security, select Authorization Schemes.

6. Click the appropriate tab at the top of the page:

   - Subscription

   - Utilization

#### Subscription

Use the Authorization Scheme Subscription report to view details about authorization schemes subscription.

#### Utilization

Use the Authorization Scheme Utilization report to view details about authorization schemes utilization.

To view additional reports indicating which pages having authorization schemes and which do not, select one of the following from the Tasks list:

- Report Pages With Authorization Schemes

- Report Pages Without Authorization Schemes